Skip to content

RAD-17385 Contract: count attempts in doubt, and mark an accepted response whose body is unknown - #90

Open
dmurphy5 wants to merge 5 commits into
masterfrom
dylan/contract-doubt-and-unknown-body
Open

dmurphy5 wants to merge 5 commits into
masterfrom
dylan/contract-doubt-and-unknown-body

Conversation

@dmurphy5

Copy link
Copy Markdown

What this adds and why

Two native changes come later. One counts the attempts whose result was in doubt. The other settles a request as accepted when the status said "accepted" but the response body did not arrive. This PR adds the TypeScript side of both: the types, the delivery rules, the fake native module, tests and docs. The native PRs then have a contract to build to.

One thing changes now: every handler's meta has ambiguousAttempts, which is 0 for today's events. A test that compares the whole meta object, and a Meta built by hand, need the new field. Nothing else changes until native sends the new fields.

Part 1: attempts in doubt

The library always sends a request again when it cannot tell if the server got it. Now it tells the app how often that happened.

  • Meta.ambiguousAttempts: number: attempts of the current generation that ended with no server answer after the whole request can have reached the server. A count above 0 means the server can have more than one copy. A missing or bad value reads 0.
  • AttemptEvent.bodySent?: 'none' | 'partial' | 'full': how much of the request body had left when the attempt ended.
onSuccess: (data, vars, meta) => {
  if (meta.ambiguousAttempts > 0) {
    analytics.track('upload sent in doubt', { key: meta.key, count: meta.ambiguousAttempts });
  }
},

Part 2: accepted, body unknown

When the server accepted a request but the library has no response body, the request is done. It is never sent again and never reported as an error. The truncated error keeps its one meaning: the body was over 1 MB.

  • RawResponse.bodyUnknown?: true. body is then undefined. Native sends a JSON boolean; JS reads any truthy value as the flag, so a wrong value never sends an accepted request to the parser.
  • No response parser: the definition gets the flag in onSuccess(raw, vars, meta), like any completed outcome.
  • Parser and onBodyUnknown: the parser and onSuccess do not run, and onError is not called. The new optional handler onBodyUnknown(response, vars, meta) runs instead. Only a definition with a parser accepts it.
  • Parser and onSuccess, no onBodyUnknown: the outcome is held, as an outcome with no definition is held today.
    • It is not acknowledged, and native keeps the row.
    • The client warns for each outcome through onWarning. The detail is the outcome, with its vars.
    • It is delivered when a define() of the key adds onBodyUnknown, or at the next launch, with meta.deliveries grown.
  • Parser and neither handler: the app asked for no result, so the outcome is acknowledged with no call and no warning.
  • Ack, replay and retry work as for any other completed outcome. The ack waits for the handler's promise, and a handler that rejects runs again at the next launch.
uploads.define({
  key: 'note.create',
  request: (vars: NoteVars) => ({ url: notesUrl(vars), data: vars.note }),
  response: (raw) => noteSchema.parse(raw),
  onSuccess: (note) => {
    store.dispatch(noteSaved(note));
  },
  // The server has the note, but its answer was lost. Fetch it.
  onBodyUnknown: (_response, vars) => {
    store.dispatch(fetchNote(vars.noteId));
  },
});

createFakeNative() settles the case with response: { bodyUnknown: true } and sets the count with the ambiguousAttempts override.

What does not change

  • No native code changes. The send decision does not change.
  • A body over 1 MB still gives truncated to a definition with a parser.
  • Existing types only gain fields. Meta.ambiguousAttempts is the one required field.

Tests

  • Jest, the hold rule:
    • Three held outcomes: none acknowledged, rows kept.
    • Release when define() adds onBodyUnknown.
    • Redelivery at the next launch through the fake, with deliveries grown.
    • The case with no handlers.
  • Jest, the rest:
    • Routing for both definition kinds.
    • A flag of 1 and of false.
    • A chunked completion.
    • A late definition.
    • An ack that waits for an async onBodyUnknown.
    • A rejected onBodyUnknown that runs again at the next launch.
    • The count and its default of 0.
  • Type tests (src/__typetests__/doubt.ts): the new fields, the onBodyUnknown types, onBodyUnknown refused without a parser, and the README examples.
  • Mutation checks: each rule was broken on purpose and a test failed each time. The breaks included acknowledging instead of holding, warning once per key, checking === true, routing to onError and running the parser.
  • Checks: yarn lint:ci, yarn typecheck and yarn test (331 tests) pass. swift test (iOS host) and the Android unit tests passed on the first version of this branch; the later commits change no native code.

Two independent review rounds were applied. Part of RAD-17385.

🤖 Generated with Claude Code

dmurphy5 and others added 5 commits November 18, 2026 11:02
…ose body is unknown

Native code will later count attempts whose result was in doubt, and settle
a request as accepted when the status said accepted but the body was not
received. This adds the TypeScript side so the native work has a contract.
Behavior does not change until native sends the new fields.

- Meta.ambiguousAttempts: the count from native, 0 when absent or malformed.
- AttemptEvent.bodySent: 'none' | 'partial' | 'full', optional.
- RawResponse.bodyUnknown: true, optional. A definition without a parser
  gets it in onSuccess. A definition with a parser gets the new optional
  onBodyUnknown(response, vars, meta) instead of the parser and onSuccess,
  never onError. With no onBodyUnknown, no handler runs, the outcome is
  acknowledged, and the client warns once per key.
- The fake native can settle the case and set the count.
- Type tests, jest tests, README, and an Unreleased CHANGELOG section.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…a parser

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…known

Before, a definition with a response parser and onSuccess but no
onBodyUnknown acknowledged the outcome with no handler call and one warning
per key. The app never learned that the server had the object. Now the
outcome is held unacknowledged, as for a key with no definition: native
keeps the row, the client warns for each outcome with the event as detail,
and the outcome is delivered when define() adds onBodyUnknown for the key or
at the next launch. A parser definition with neither onSuccess nor
onBodyUnknown asked for no result, so it is still acknowledged with no call.

Any truthy bodyUnknown now counts as the flag, so a wrong value never sends
an accepted request to the parser with no body. Native sends a JSON boolean.

Tests: three held outcomes with rows kept, release in the same session, a
real redelivery at the next launch through the fake, the quiet case, a
truthy flag of 1, a chunked completion, a late definition, and an ack that
waits for an async onBodyUnknown. Renamed two tests to what they show.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
- CHANGELOG states the one change today: meta.ambiguousAttempts is 0.
- README: the retry-table row says native does not send the flag yet; the
  hold rule; an onSuccess that reads body without the check throws once
  native sends the flag; handler examples use block bodies.
- Type tests compile the README examples.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
- README: this hold emits no state event, the row stays completed until the
  ack, and the onWarning warning (with the event as detail) is the signal.
  It is an exception to the order per id. The list of reasons a completed
  row stays now includes it.
- The fake's settle() doc and its timeout message name the case.
- The createDelivery and release() comments cover both holds.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant